AccordionBox

• Source Code and Options
• Number of sims that use this component: 61

General Design Considerations

Here’s when and why we use accordion boxes:

• Default state can be expanded or collapsed depending on how the designer wants to scaffold the user interaction. A closed panel can be used to keep the default opening condition of sim from being visually overwhelming, and suggesting a logical route for exploration, for example in Build an Atom and in GE:B (please spell out simulation name).
• Accordion boxes can also be useful for teachers to ask predictive questions.
• Can contain non-interactive readouts, interactive controls, but not sprites (e.g., draggable toolbox items).

Note this design pattern covers multiple PhET Component Types

• AccordionBox.js
• ExpandCollapseBar.js
• ExpandCollpaseButton.js

Aesthetic Considerations

• If space is a concern, the title can be hidden while the accordion box is expanded. Note that an accessible name for the title is always needed and available for the non-visual experience.
• An expanded accordion box cannot overlap other elements when opened (unlike combo box, for instance).
• Always includes an iconed button (+/-), typically to the left of the title.
• Other sim content does not fill the space when an accordion box is collapsed.
• The accordion box content can be expanded or collapsed by default and a change of state for one accordion does not affect the state of other accordion boxes.

Accessibility Considerations

Accessible Components of an Accordion Box

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

• Accordion Header: Label (usually a heading with a +/- icon signalling expand/collapse behaviour) for a section of content (usually a collapsible box). The accordion header could also be an icon, alone. The accordion header serves as a control that can show or hide a section of content.

• Accordion Panel: Section of content (e.g., the content box) associated with an accordion header

• Typically, has a visual title with an icon that indicates expanded and collapsed state.

  • The title may disappear when box is expanded.
  • Focus highlight would go around title in both the expanded and collapsed states, if title remains visible.
  • If title visually disappears when expanded, the focus highlight would be limited to the open/close icon and the designer would need to consider extra padding to ensure a reasonable clickable area.
  • It is possible that the focus highlight can change size when toggling between expanded/collapsed states in the scenario when the expanded box does not have a title.
• The typical structure is a button nested within the parent titling element, likely a heading.
• Typically, the open/close icon does not need to be represented in the Parallel DOM.
• For accessibility the expanded and collapsed states of the box are communicated through a combination of ARIA attributes, aria-expanded, aria-controls, aria-hidden that have to be managed through javascript.

Gesture Support

ToDO.

Keyboard Support

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

QUESTION: It's not clear to me how users get inside a panel, if the panel has no focusable items.

Management of Role, Property, State, and Tabindex Attributes

Adapted from: ARIA Pracrices 1.1, section 3.1 Accordion

DRAFT: Sample HTML

<! -- expanded state -->
    <h3>
       <button id="accordion-header-01" aria-expanded="true">Factors</button>
    </h3>
    <div id="accordion-panel-01" role="region" aria-labelledby="accordion-header-01">
       <p>Box content.</p>
       <p>More content or even other HTML controls.</p>
    </div>
<! -- collapsed state -->
  <h3>
     <button id="accordion-header-02" aria-expanded="false">Product</button>
  </h3>
  <div id="accordion-panel-02" role="region" aria-labelledby="accordion-header-02" aria-hidden="true">
     <p>Box content.</p>
     <p>More content or even other HTML controls.</p>
  </div>

Supporting Accessibility Resources

• Adapted from ARIA Practices 3.1 Accordion (Sections With Show/Hide Functionality)

Design Doc Content Template Text

Accordion Box

• Accordion Box Title (header):
• Accessible Name: content for the accordon box title
  • Header contains a title? Yes/No, default Yes - actually, title for header should be required.
  • Title is a heading? Yes/No, defaults to Yes
  • If title is heading, set heading level, defaults to H3
  • Accordion title is visually hidden: Yes/No (defaults to No)
• Accordion Box Content (panel):
  • Parent container accordion box contents: defaults to a div
  • Use same convention as other objects and controls.
  • Default open state: expanded/collapsed (defaults to expanded)

Checkbox

• Source Code and Options
• Number of sims that use this component: 90

General Design Considerations

Here’s the when and why we use a checkbox (traditional looking checkbox user interface component) in simulation design.

• Generally, when a secondary or non-essential option needs to be toggled between on and off states
• To toggle more than one option in a group of options
• Checkboxes are often used to allow users to layer on more complex representations, or to view multiple, related represenations simultaneously. More complex options are generally off by default.

Note this design pattern covers multiple PhET Component Types

• Question: Are there any other types of visual checkboxes?

Aesthetic Considerations

• Checkbox appears checked or not checked on simulation load
• Appears with a text-based label, or an icon as the label, or a combination of both text and icon
• Title case is used for text-based labels for checkboxes

Accessibility Considerations

• HTML checkboxes (i.e., input type="checkbox") and possibly all visual PhET sim checkboxes are two-state controls that represent the element's "checkedness" state.
• Traditional looking checkboxes with visual labels are generally best represented in the PDOM as an input of type checkbox with an associated label element.
• When the visual label content is an image or a string of text that does immediately translate into a name that clearly communicates what the checkbox is for, non-visually, consider changing the visual string, adding clarifying help text, or providing a more descriptive name as the label element's content in the PDOM. Keep in mind that ideally, the visual text and the text in the PDOM should be the same to support users who use voiced commands.
• Groups of related checkboxes may benefit from being explicitly grouped using a containing element (e.g., fieldset or div) with the ARIA role="group". Grouping checkboxes is optional.
• Explicitly grouped checkboxes may benefit from a group name provided by either an h3 or a legend.
• Checkboxes that appear visually grouped (e.g., by proximity or with a visual box) for convenience or space-saving may not benefit from explicit group semantics in the PDOM.
• When a group is very important, consider using a heading, e.g., h3 as headings are placed in the heading outline which can be navigated with screen reader software whereas the legend element is not placed in the heading hierarchy.

Note: Known issue that some screen readers (i.e., VoiceOver) repeat the checkbox's label content when the label is associated with the input via the for attribute. We discovered that we do not get repetition of the label content when the label comes before the checkbox. When there is no visible screen label, the aria-label attribute is an option, and it also does not cause any repetition.

Gesture Support

ToDO.

Keyboard Support

Management of Role, Property, State, and Tabindex Attributes

Respecting the first rule of ARIA, "use a native HTML element whenever possible", we use native checkbox elements in the PDOM to represent traditional looking checkbox interactions. An HTML checkbox could represent other "switching" interactions that may not visaully look like a checkbox in the simulation, but examples for those are provided elsewhere. Because we use native HTML for checkbox interactions, some of the guidance provided in ARIA Practices for checkbox widgets is not relevant. I have adapted the content from the ARIA practices section for checkbox.

• No explicit ARIA role of checkbox is needed on an native HTML checkbox (input type="checkbox").
• No tabindex required, native HTML checkboxes are focusable elements.
• An HTML checkbox has an accessible label (i.e., accessible name) provided by one of two of the following ways:
  • Visible text content contained within a label element and assocaited to its input with the for attribute.
  • Content within an aria-label attribute set on the input element with type="checkbox".
• When checked, the checkbox element has the attribute checked present.
• When not checked, the checked attribute is not present.
• When partially checked, it has state aria-checked set to mixed. (tri-state checkboxes only)
• When a set of checkboxes is presented as a logical group with a visible label, the checkboxes are included in an element with role="group" that has the property aria-labelledby set to the ID of the element containing the label or name for the group.
• When the presentation includes additional descriptive static text (i.e., help text) relevant to a checkbox or group of checkboxes, using aria-describedby is an option to provide automatically read help text. We have, however, that automatic helptext is not needed in our sims. Users seem to prefer on-demand help text.

Simplified HTML Examples for PDOM

Options for Checkbox in the A11y API

When creating the common code component, it would be useful to have options to use either a label element or an aria-label attribute to provide the accessible name for the checkbox.

Checkbox with visual label text

Energy Forms and Changes

Visual checkbox with a text-based label:

State Descriptions

<input id=”energy-symbols” type=”checkbox”> <!-- not checked checkbox-->
<label for=”energy-symbols”>Energy Symbols</label>
<p>Observe energy chunks move and change through system.</p>

Responsive Descriptions

• When checked: Symbols flow with energies.
• When unchecked: Energy symbols hidden.

Checkbox without visual label text (option with aria-label)

Area Model Introduction

Visual checkbox with different label

<input id="counting-numbers" type="checkbox" aria-label="Counting numbers">
<p>Use area grid with or without counting numbers in grid cells.</p>

Unnamed group of checkboxes

Gravity Force Lab

Note: still need to finish this example.

<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Constant Size</label>
<p>When changing mass, observe constant or changing size of spheres.</p>

<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Force Values</label>
<p>Explore value of forces in newtons.</p>

<input id=”” type=”checkbox”> <!-- not checked checkbox-->
<label for=””>Scientific Notation</label>
<p>Listen to newtons in scientific notation.</p>

Supporting Accessibility Resources

• Using ARIA, working draft
• HTML5.1, Section 4.10.5.1.15. Checkbox state
• ARIA Practices 1.1 Section 3.6 Checkbox

Checkbox Snippet for Design Document

{{checkbox name}}, checkbox

• Accessible Name:
• Interaction Type: checkbox or non-visual checkbox
• Initial State: checked/ not checked
• (Optional) Help Text:
• (Optional) Context responses or link to section with context responses.
• (Optional) Design Note: Special things about this checkbox, if any.

ComboBox

• Source Code and Options
• Number of sims that use this component: 38

General Design Considerations

• Generally used with limited space and/or a long list of choices
• PhET comboboxes are not auto-select when hovering options with a mouse or when navigating through options with the arrow keys (i.e., different from radio button lists)
• Label for control serves a dual purpose: identifies the combobox (list of options) and identifies the selected option
• Selected item is communicated clearly upon focus and when the list is closed
• Large pointer/click areas: box label and selected item; option labels and images

Aesthetic Considerations

• List can appear above or below the button depending on space considerations
• Can include an indicator image (to the left of the list item)
• The rounded corners of the list should match the rounded corners of the button
• Generally, the list panel is often the same width as the button
• Mouse hover and focus highlights should be considered together

Accessibility

The PhET combobox interaction, visually looks and behaves as a combobox in the sense that a list of hidden options can be revealed on demand; however, the accessible representation that we have found to work nicely is actually a button, which may have a dynamic label (i.e., accessible name) that pops up a listbox with a list of options. Design and interaction details are below.

Gesture Support

ToDO.

Keyboard Support

Role, Property, State, and Tabindex Attributes

(adjusted content from W3C listbox collapsible example, see https://www.w3.org/TR/wai-aria-practices-1.1/examples/listbox/listbox-collapsible.html)

Sample HTML for Combobox

The PhET combobox interaction, visually looks and behaves as a combobox; however, the ARIA 1.1 Combobox design pattern wasn't and will never be supported. For the accessible representation in the Parallel DOM we implemented this widget as a dynamic button and a popped-up listbox (Bryan Garanventa, 2016). The HTML example is below.

Note: The HTML for this interaction may change when the ARIA role combobox has better support accross assitive technologies.

Molarity Example (10 options)

    <div tabindex="-1" id="container-for-labels">
    <span id="listbox-static-label">Solute</span>
      <button id="listbox-option-dynamic-label" tabindex="0" aria-haspopup="listbox" aria-labelledby="listbox-static-label listbox-option-dynamic-label">Drink Mix</button>
    </div>
    <ul role="listbox" tabindex="0" id="listbox" aria-activedescendant="option-1" aria-labelledby="listbox-static-label" style="list-style:none;">
      <li role="option" id="option-1" class="selected" aria-selected="true">Drink mix</li>
      <li role="option" id="option-2">Cobalt (II) nitrate</li>
      <li role="option" id="option-3">Cobalt Chloride</li>
      <li role="option" id="option-4">Potassium dichromate</li>
      <li role="option" id="option-5">Gold (III) chloride</li>
      <li role="option" id="option-6">Potassium chromate</li>
      <li role="option" id="option-7">Nickel (II) chloride</li>
      <li role="option" id="option-8">Copper sulfate</li>
      <li role="option" id="option-9">Potassium permanganate</li>
      <li role="option" id="option-10">Potassium dichromate</li>
    </ul>
    <!-- help text for combobox -->
    <p>Change a solute and observe differences.</p>

Supporting Accessibility Resources

• Adapted from ARIA Practices Collapsible Listbox Example( 2016)
• The above pattern has been adopted as the 1.2 Combobox design pattern( 2022)

Design Doc Content Template Text

{{Name of combobox}}, combobox

Accessible Name (dynamic): Text + {{Name of Selected list item}} (e.g. Solute: {{Drink Mix}})

Interaction Type: Combobox (i.e., Combobox.ts composed of subcomponents ComboBoxButton.ts (tagName: 'button') and ComboBoxListBox.ts (ariaRole: 'listbox')

Button Label with initial selection:

Listbox list items:

• List Item 1 (e.g., Drink Mix)
• List Item 2 (e.g., Cobalt (II) nitrate)
• List Item 3

(Optional) Help Text:

(Optional) Link to section with object & context responses

(Optional) Design Note: Special things about this combobox, if any.

RectangularRadioButtonGroup

• Source Code and Options
• Number of sims that use this component: 66

No markdown content for RectangularRadioButtonGroup yet.

RoundPushButton

• Source Code and Options
• Number of sims that use this component: 125

No markdown content for RoundPushButton yet.

RectangularPushButton

• Source Code and Options
• Number of sims that use this component: 109

No markdown content for RectangularPushButton yet.